feat(land): the quest watcher bumps quest's pin in other repositories - #550

Part of quest/m0/pin-sync.md: every push to quest's main now reaches each repository that pins quest without anyone touching it. The host half (the watcher's --bump flags and system.autoUpgrade) is a kixelated/nixos PR. This PR rewrites the quest to that remaining host work and the maintainer-only steps.

Builds on moq-dev/quest#540, now merged into main.

Decisions

• Round-3 design checkpoint, how an ungated bump judges a run that a newer run cancelled (maintainer, 2026-11-08, through /quest-unblock, comment): ✅ continue, judging only each workflow's latest run per workflow and event, so a run cancelled because a newer run replaced it counts as replaced, not failed (rejected: stop merging bumps on ungated bases; rethink the targets, giving kixel.ai a required check and pushing nixos's bump straight to main; merge as is). As implemented, a cancelled run also yields to a newer run of its workflow from the other event, since the case that raised it is a cancel-in-progress group shared across push and pull_request, and the replaced run's check runs are dropped with it, so a later job it never started can't fail the bump.

What changed

• quest land watch --bump <owner/repo> (repeatable, new src/cli/land-bump.ts). After its queue pass, each pass reads the watched base's commit. For each target that doesn't pin it yet, the watcher opens or updates that target's one quest-bump PR as the App:
  • It reads the target's flake.lock on its default branch and finds the one root input that locks the watched repository. A target already at the commit gets nothing, and an open bump PR there is closed with a comment.
  • In a fresh checkout that borrows its objects from a bare per-target cache with the base's whole history (so quest check --fix sees deleted quests, and later fetches are incremental), it unpins the URL in flake.nix (github:moq-dev/quest/<rev> becomes github:moq-dev/quest), so later bumps change only the lock. It then locks the input to the exact commit with nix flake lock --override-input.
  • It builds that commit's quest with nix build, then runs its quest init and quest check --fix in the checkout.
  • It commits as moq-bot and lease-pushes. When a bump PR is already open, the new commit is a merge of that PR's head and the base, with the fresh bump as its tree, so the branch never needs a force push. Auto-merge is disarmed before the push, the PR is re-read so one that closed meanwhile restarts the bump next pass, and a PR left on an old default branch is retargeted.
  • The body links the comparison and records the review as skipped (Skipped: pin bump, no repository code changed; CI's quest check is the gate.).
  • Findings --fix can't resolve leave the PR a draft with a ## Waiting item. Otherwise the PR lands through quest merge's own path (land()): GitHub's merge queue, the quest land gate or own queue, or auto-merge.
  • On a base that requires no checks, land() would merge immediately. There the bump first waits for every check on its head to pass (only each workflow's latest run per event counts, and a run a newer one cancelled counts as replaced), then merges directly if the repository has no auto-merge (kixelated/nixos, a private repository on GitHub Free). A failed check or a refused landing gets a comment and is left for a maintainer.
  • bump.json in the state directory records each step, so a restart repeats nothing, a failed landing never re-pushes, and a bump someone closed isn't reopened for the same commit. One target's failure doesn't hold up the others; the pass reports it and the daemon retries.
• requirements() (used by quest merge): a private repository on GitHub Free answers GET /rules/branches with a 403 upgrade notice. That now reads as "no rules" instead of failing. On kixelated/nixos, quest merge now gives its usual "auto-merge disabled" refusal instead of an HTTP 403.
• README: new "Pin bumps" section under the watcher.

Public API

• New quest land watch --bump <owner/repo> option. The watcher refuses to start with it when nix isn't on PATH, or when it names the watched repository itself. Nothing else changes for existing invocations.
• quest merge on a private repository on GitHub Free: refusal message instead of an HTTP 403 (above).
• Each target's App token asks for contents: write, pull_requests: write, merge_queues: write, and read access to administration, checks, and statuses, plus workflows: write only for a push that carries a workflow change. All of these are within moq-bot's existing moq-dev installation. Nix reads GitHub with the watched repository's contents: read token.

Choices made without asking

• One central pass in the quest repository's watcher, minting a token per target, rather than each repository's daemon bumping itself. The trigger is the watcher's own base, quest builds once per commit, and the pass covers targets with no land daemon (kixelated/nixos, studio, kixel.ai). The target list is just the --bump flags. The nixos module derives it from the enrolled land repositories, plus studio, kixel.ai, and nixos.
• The bot unpins rev-pinned URLs on its first bump of each repository, following the quest's recommendation. moq, studio, kixel.ai, rind, rust2, and nixos pin a revision in flake.nix today.
• The bump runs quest at the new commit, built by Nix. Using the watcher's own binary would write stubs from an older quest whenever the host lags behind quest's main. That code runs as the daemon user, which can read the App key. It's the same trust the daemon already places in reviewed main.
• A newer bump replaces the PR's tree. A land fixer's commit on an older bump (such as moq.pro's instruction-budget fix in its manual bump) is dropped, and the target's fixer redoes it if the new bump needs it.
• Ungated bases wait for every check, not just required ones. kixel.ai's only check is CodeRabbit (a neutral status), so its bumps merge once CodeRabbit reports.
• Not added: compare-based ordering (the bot follows main even if a target pins a commit main doesn't contain), and a timeout on Nix commands (repository rule: no timeouts as workarounds).

Validation

• just check and just test pass (1219 passed and 5 skipped, plus 562 passed), after merging origin/main.
• Review fixes so far: the bump's quest runs from a directory of its own with --root (a target's bunfig.toml preload never loads); a checkout with a tracked symlink that leaves it or dangles is refused; an ungated bump waits for the head's workflow runs and for other apps' check suites; unpinning matches case-insensitively. The target token now also asks for actions: read.
• test/land-bump.test.ts runs the pass against a fake GitHub and a local target repository with Nix and quest faked. It covers:
  • opening and queueing a bump, then a no-op second pass with no requests;
  • moving an open bump forward with a merge, after disarming auto-merge;
  • a findings draft;
  • closing a bump the base already pins;
  • an ungated base waiting for its checks before a direct merge;
  • a failed check left for a maintainer;
  • a run a newer run cancelled counting as replaced, and latestRuns's choice per workflow and event;
  • a symlink whose name holds a tab, full history for quest check --fix, a PR that closes mid-bump, and retargeting to a new default branch, and rebuilding a cached quest that Nix's garbage collection removed;
  • one failing target not holding up the others;
  • the GitHub Free 403 in requirements().
• Live run of the real hostTools against a shallow clone of moq-dev/studio (nothing pushed): it found input quest at 1c3cf6a pinned in flake.nix, unpinned it, locked it to 6f20c25 (flake.lock 4 lines added and 5 removed), built quest, and ran quest init (nothing to change) and quest check --fix (35 documents ok).

Suggested follow-ups

• None recommended beyond the rewritten quest's remaining host work.

Review

Rewritten by quest review after each round.

• Reviewer: Codex, gpt-6.1-sol, xhigh effort
• Session: 01a1b980-e3ee-7eb2-958a-fd82f75b9c42, round 4
• Head: c73bca7
• Base: origin/main at a1d71f7
• Score: 10/10, The cache rebuild change introduces no findings; targeted read-only checks and diff checks passed, while full suites were not run in the read-only sandbox.
• Findings: none

Models

• Size: L
• Implementer: Claude Code, claude-opus-5-5, high effort
• Implementer: Claude Code, claude-opus-5-5, low effort (iterate, L)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)